PlotIconID

PlotIconID
Header:	Icons.h		Carbon status:	Supported

Draws the icon described by an icon family.

OSErr PlotIconID (
    const Rect *theRect, 
    IconAlignmentType align, 
    IconTransformType transform, 
    SInt16 theResID
);

theRect

A pointer to the rectangle, specified in local coordinates of the current graphics port, in which to draw the icon.

You cannot determine which icon from the family specified by theResID the function will draw. The function determines, from the size of the specified destination rectangle and the current bit depth of the display device, which icon of a given size to draw from an icon family. For example, if the destination rectangle has the coordinates (100,100,116,116) and the display device is set to 4-bit color, the function draws the icon of type 'ics4' if that icon is available in the icon family.

If the width or height of a destination rectangle is greater than or equal to 32, the function uses the 32-by-32 pixel icon with the appropriate bit depth for the display device. If the destination rectangle is less than 32 by 32 pixels and greater than 16 pixels wide or 12 pixels high, PlotIconID uses the 16-by-16 pixel icon with the appropriate bit depth. If the destination rectangle’s height is less than or equal to 12 pixels or its width is less than or equal to 16 pixels, PlotIconID uses the 12-by-16 pixel icon with the appropriate bit depth. (Typically only the Finder and Standard File Package use 12-by-16 pixel icons.)

The destination rectangle must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for the function to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, the function expands or shrinks the icon to fit.

align

Specifies how the function should align the icon within the rectangle. For example, you can specify that it center the icon within the rectangle or align it at one side or the other. The function moves the icon so that the edges of its mask align with the specified side or direction. See “Alignment Type Values” for a description of the values you can use here.

transform

Specifies how the function should modify the appearance of the icon. See “Transform Type Values” for a description of the values you can use here.

theResID

The resource ID of the icon to draw. The icon resource must be of resource type 'ICN#', 'ics#', 'icl4', 'icl8', 'ics4', or 'ics8'. In general, you should specify your icon resources as purgeable.

function result: A result code.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.